.\" Copyright 2008-2010 Vadim Zhukov <persgray@gmail.com>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY AGAVA COMPANY ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
.\" EVENT SHALL THE AGAVA COMPANY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" The views and conclusions contained in the software and documentation are
.\" those of the authors and should not be interpreted as representing official
.\" policies, either expressed or implied, of the AGAVA Company.
.Dd $Mdocdate$
.Dt RB_AGENT 1
.Os AGAVA
.Sh NAME
.Nm rb_agent
.Nd backups management agent \&to \&be run \&on a remote host
.Sh SYNOPSIS
.Nm rb_agent
.Op Ar verbose
.Ar command
.Oo
.Op Ar param\&=value ...
--
.Ar which
.Op Ar ...
.Oc
.Sh DESCRIPTION
The
.Nm
utility is called via SSH by
.Xr rb_dump 1 ,
.Xr rb_restore ,
and
.Xr rb_cpanel 1 .
It should not be called manually except for testing purposes.
Command line parameters as follows:
.Bl -tag -width "param=value"
.It Ar verbose
If first command line parameter is
.Dq verbose ,
then verbose mode is turned on.
In verbose mode agent will print many information about what it is doing at the
moment.
This can help while debugging different problems.
.It Ar command
Commands supported:
.Bl -tag -width "restore"
.It Dv dump
Dumps item(-s) requested in one
.No ( Va separate_archives
is disabled) or many
.No ( Va separate_archives
is enabled) archives which are sent on-the-fly to standard output.
.It Dv put
Recieves an archive(-s) from a backup server and put it to a directory specified
in the
.Va workdir
parameter.
If
.Va workdir
parameter isn't specified then archive will be put in current directory. If
.Va separate_archives
is set then many archives could be recieved and put in, creating subdirectories
if neccesary.
.It Dv restore
Reads one or more archives from the input and restore contained items.
Archives are not saved. on disk.
.It Dv version
Prints a string that looks like:
.\" Do not use .Nm macro because agent sends always "rb_agent" string, not its
.\" program name.
.Dl rb_agent version 2.22
and exit.
This command is used for comparing agent versions on a backup server and
remote host.
This is the only command that doesn't need any additional parameters.
.El
.It Ar param=value
Different parameters that agent uses for data retriveing and/or sending.
Basically they consists of backup module options and a few extra options,
such as
.Va separator
(used when sending or receiving archives when
.Va separate_archives
is enabled to mark archives boundaries and metadata, such as archive name).
End of parameters should be marked by
.Cm -- .
.It Ar which
Contains item names to dump.
Not used for putting: item names are sent in the same stream as archives.
Restoring doesn't need to know item names at all, archives are unpacked
on-the-fly.
.Pp
Item names are sent in a Base64 encoding.
It's simplier than trying to carefully escape shell characters.
And it's unlikely to overrun maximum command line, even with
.Va separate_archives
enabled for children of directory with 1000+ items.
.El
.Sh VERSION CONTROL
To avoid problems caused by version incompatibles between
.Xr rb 7
tools connecting to agent and agent itself, each time a tool connects to host
it checks for agent version.
Agent version consists of major and minor version.
So there same rules applied as for shared libraries: agent should has same
major version and same or higher minor version.
If agent version is incompatible, agent is replaced with one from tools bundle
(it's assumed that
.Nm
lives in the same directory as tool).
.Sh SEPARATE ARCHIVES
While sending or retrieving single archive isn't something hard, multiple
archives in a single stream require a bit more work.
.Xr rb 7
uses the following method for this: stream is broken into chunks of a fixed size
(currently, 65536 bytes), with padding if needed.
Each chunk is either
.Dq data
chunk or
.Dq special
chunk.
Each data chunk consists of archive data only.
Special chunks are marked by value of
.Va separator
at their start and some meta information follows it.
Such metadata may consists of archivied item name and archive size.
Size is used to remove padding (if any) from last archive's data chunk.
.Pp
Protocol is not the same in both directions (sending data from and to agent).
The main reason is that we do not know size of archive when it is created, so
we send size information after archive itself. But when putting archive we
already know this size, and ever may need this information \(en to reserve space
for archive before dumping it. Such behavior doesn't present there still, but
could be implemented in the future.
.Sh SEE ALSO
.Xr rb_cpanel 1 ,
.Xr rb_dump 1 ,
.Xr rb_restore 1 ,
.Xr ssh 1 ,
.Xr rb 7 .
.Sh AUTHORS
The
.Nm
manual page was written by
.An Vadim Zhukov Aq persgray@gmail.com .
.Sh HISTORY
An
.Nm
utility appeared in
.Nm RB
toolkit 1.0.